@openim/im-composer 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-12-29
+
+### Added
+
+- **Dual Mode Support**: Plain text and Rich text (Markdown) modes
+- **@Mentions**: Type `@` to search and mention users with customizable provider
+- **Attachments**: Paste or drag files with image preview (plain mode)
+- **Quote Messages**: Reply to messages with quote blocks (plain mode)
+- **Emoji Support**: Full Unicode emoji with optional Twemoji integration
+- **Draft Support**: Save and restore editor state with `getDraft()`/`setDraft()`
+- **Rich Text Features**:
+  - Formatting toolbar (bold, italic, strikethrough, code)
+  - Headings (H1, H2, H3)
+  - Lists (bullet and ordered)
+  - Code blocks
+  - Block quotes
+  - Links with click-to-edit popup
+  - Image upload and embedding
+- **i18n Support**: Customizable locale for all text labels
+- **Keyboard Shortcuts**:
+  - Configurable send key (Enter / Ctrl+Enter / Cmd+Enter)
+  - Markdown shortcuts (e.g., `**bold**`, `# heading`)
+  - Link shortcut (Cmd/Ctrl + K)
+- **Ref Methods**: Focus, clear, export, import, insert text, and more
+- **TypeScript**: Full type definitions included
+
+### Dependencies
+
+- Built on [Lexical](https://lexical.dev/) editor framework
+- Requires React 18+ or 19+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 im-composer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,308 @@
+# @openim/im-composer
+
+A React IM composer component with dual mode (plain/rich) supporting @mentions, emoji, attachments, and markdown.
+
+Built with [Lexical](https://lexical.dev/) editor framework.
+
+## Installation
+
+```bash
+npm install @openim/im-composer
+# or
+pnpm add @openim/im-composer
+```
+
+**Note:** Requires React 18+ or React 19+ as peer dependencies.
+
+## Quick Start
+
+```tsx
+import { IMComposer, IMComposerRef } from '@openim/im-composer';
+import '@openim/im-composer/styles.css';
+
+function Chat() {
+  const composerRef = useRef<IMComposerRef>(null);
+
+  return (
+    <IMComposer
+      ref={composerRef}
+      mode="plain"
+      placeholder="Type a message..."
+      onSend={(payload) => {
+        console.log('Sent:', payload);
+      }}
+      mentionProvider={async (query) => {
+        // Return list of users matching query
+        return [{ userId: '1', display: 'John', avatarUrl: '...' }];
+      }}
+    />
+  );
+}
+```
+
+## Features
+
+### Plain Text Mode
+- **@Mentions** - Type `@` to search and mention users
+- **Attachments** - Paste or drag files with preview
+- **Quote Messages** - Reply to messages with quote blocks
+- **Emoji** - Full Unicode emoji support
+- **Draft Support** - Save and restore editor state
+
+### Rich Text Mode (Markdown)
+- **Formatting Toolbar** - Bold, italic, strikethrough, code
+- **Headings** - H1, H2, H3
+- **Lists** - Bullet and ordered lists
+- **Code Blocks** - Inline code and code blocks
+- **Block Quotes** - Quote formatting
+- **Links** - Insert and edit links with popup
+- **Images** - Upload and embed images
+
+## Props
+
+### Basic Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `mode` | `'plain' \| 'rich'` | - | Controlled mode |
+| `defaultMode` | `'plain' \| 'rich'` | `'plain'` | Default mode (uncontrolled) |
+| `onSend` | `(payload) => void` | - | Callback when user sends message |
+| `placeholder` | `string \| { plain?: string; rich?: string }` | - | Placeholder text |
+| `disabled` | `boolean` | `false` | Disable the editor |
+| `className` | `string` | - | Custom class name |
+| `onChange` | `() => void` | - | Callback on content change |
+
+### Mention Options (Plain Mode)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enableMention` | `boolean` | `true` | Enable @mention feature |
+| `mentionProvider` | `(query: string) => Promise<Member[]>` | - | Async function to search members |
+| `maxMentions` | `number` | - | Maximum mentions allowed |
+| `renderMentionItem` | `(props) => ReactNode` | - | Custom render for mention dropdown items |
+
+### Attachment Options (Plain Mode)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enableAttachments` | `boolean` | `true` | Enable file attachments |
+| `showAttachmentPreview` | `boolean` | `true` | Show built-in attachment preview bar |
+| `attachmentPreviewPlacement` | `'top' \| 'bottom'` | `'bottom'` | Position of preview bar |
+| `maxAttachments` | `number` | `10` | Maximum attachments allowed |
+| `maxFileSize` | `number` | - | Maximum file size in bytes |
+| `allowedMimeTypes` | `string[]` | - | Allowed MIME types |
+| `onAttachmentLimitExceeded` | `(reason, file) => void` | - | Callback when limit exceeded |
+| `onFilesChange` | `(attachments) => void` | - | Callback when attachments change |
+
+### Rich Mode Options
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `uploadImage` | `(file: File) => Promise<{ url: string; alt?: string }>` | - | Image upload function |
+| `markdownOptions.enabledSyntax` | `MarkdownSyntaxOptions` | All enabled | Enable/disable specific markdown features |
+
+### Keymap Options
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `keymap.send` | `'enter' \| 'ctrlEnter' \| 'cmdEnter'` | `'enter'` | Key to send message |
+
+### Other Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `onContextMenu` | `MouseEventHandler` | Right-click handler |
+| `onQuoteRemoved` | `() => void` | Callback when quote is removed |
+| `locale` | `IMComposerLocale` | i18n configuration |
+
+## Ref Methods
+
+Access via `useRef<IMComposerRef>()`:
+
+```tsx
+const composerRef = useRef<IMComposerRef>(null);
+
+// Focus the editor
+composerRef.current?.focus();
+
+// Clear content
+composerRef.current?.clear();
+
+// Export payload without sending
+const payload = composerRef.current?.exportPayload();
+
+// Insert text at cursor
+composerRef.current?.insertText('Hello 👋');
+```
+
+### All Methods
+
+| Method | Description |
+|--------|-------------|
+| `focus()` | Focus the editor |
+| `clear()` | Clear editor content and attachments |
+| `exportPayload()` | Export current payload without sending |
+| `importMarkdown(markdown)` | Import markdown content (rich mode) |
+| `getAttachments()` | Get current attachments (plain mode) |
+| `setAttachments(attachments)` | Set attachments (plain mode) |
+| `addFiles(files)` | Add files to attachments (plain mode) |
+| `removeAttachment(id)` | Remove attachment by ID (plain mode) |
+| `clearAttachments()` | Clear all attachments (plain mode) |
+| `insertQuote(title, content)` | Insert a quote message (plain mode) |
+| `insertMention(userId, display)` | Insert a mention (plain mode) |
+| `getDraft()` | Get draft state for saving |
+| `setDraft(draft)` | Restore draft state |
+| `setText(text, mentions?)` | Set editor content from plain text |
+| `insertText(text)` | Insert text at cursor position |
+
+## Payload Types
+
+### Plain Text Payload
+
+```typescript
+type PlainMessagePayload = {
+  type: 'text';
+  plainText: string;        // Text with @mentions as @{display}
+  mentions: MentionInfo[];  // Position info for each mention
+  attachments: Attachment[];
+  quote?: QuoteInfo;
+};
+```
+
+### Markdown Payload
+
+```typescript
+type MarkdownMessagePayload = {
+  type: 'markdown';
+  markdown: string;  // Full markdown content
+};
+```
+
+## i18n / Localization
+
+Customize text labels with the `locale` prop:
+
+```tsx
+<IMComposer
+  locale={{
+    linkDialog: {
+      textLabel: '文本',
+      urlLabel: '链接',
+      cancelButton: '取消',
+      insertButton: '插入',
+      saveButton: '保存',
+    },
+    toolbar: {
+      bold: '粗体',
+      italic: '斜体',
+      link: '插入链接',
+      image: '插入图片',
+      // ... more toolbar labels
+    },
+  }}
+/>
+```
+
+## Draft Support
+
+Save and restore editor state for drafts:
+
+```tsx
+// Save draft
+const draft = composerRef.current?.getDraft();
+localStorage.setItem('draft', JSON.stringify(draft));
+
+// Restore draft
+const saved = localStorage.getItem('draft');
+if (saved) {
+  composerRef.current?.setDraft(JSON.parse(saved));
+}
+```
+
+## Markdown Syntax Control
+
+Enable/disable specific markdown features:
+
+```tsx
+<IMComposer
+  mode="rich"
+  markdownOptions={{
+    enabledSyntax: {
+      heading: true,
+      bold: true,
+      italic: true,
+      strike: true,
+      codeInline: true,
+      codeBlock: true,
+      quote: true,
+      list: true,
+      link: true,
+      image: true,  // Requires uploadImage prop
+    },
+  }}
+/>
+```
+
+## Custom Mention Item Rendering
+
+```tsx
+<IMComposer
+  mentionProvider={searchUsers}
+  renderMentionItem={({ member, isSelected }) => (
+    <div className={`mention-item ${isSelected ? 'selected' : ''}`}>
+      <img src={member.avatarUrl} alt="" />
+      <span>{member.display}</span>
+    </div>
+  )}
+/>
+```
+
+## Styling
+
+Import the default styles:
+
+```tsx
+import 'im-composer/styles.css';
+```
+
+Customize with CSS variables or override the classes:
+
+```css
+.im-composer {
+  --im-composer-border-color: #e0e0e0;
+  --im-composer-focus-color: #1890ff;
+}
+```
+
+## Exported Types
+
+```tsx
+import type {
+  IMComposerProps,
+  IMComposerRef,
+  IMComposerLocale,
+  PlainMessagePayload,
+  MarkdownMessagePayload,
+  MessagePayload,
+  Member,
+  MentionInfo,
+  Attachment,
+  QuoteInfo,
+  ComposerMode,
+  UploadImageFn,
+  UploadImageResult,
+  MarkdownSyntaxOptions,
+  SendKey,
+} from 'im-composer';
+```
+
+## License
+
+This package is licensed under the MIT License.
+
+## Note on Emoji Rendering
+
+This package uses CSS font-family declarations for emoji rendering. For consistent emoji display across platforms:
+
+1. Include an emoji font (like Twemoji) in your project
+2. If using Twemoji graphics, ensure proper attribution per CC BY 4.0 license